<!-- .\" @(#)$Id: papi_sprofil.html,v 1.12 2004/10/04 16:43:14 terpstra Exp $ -->
<!-- .TH PAPI_sprofil 3 "September, 2004" "PAPI Programmer's Reference" "PAPI" -->
<HTML>
<HEAD>
<TITLE>
Manual Page - PAPI_sprofil(3)</TITLE>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">

<STYLE TYPE="text/css">

<!--

p

{font-family: Verdana, Helvetica, Arial, sans-serif}



.style

{font-family: Verdana, Helvetica, Arial, sans-serif}



td.navBar A:link

{color: #ddd8d2;

font-weight: bold;

text-decoration: none}



td.navBar A:visited

{color: #ccc9c5;

font-weight: bold;

text-decoration: none}



td.navBar A:hover

{color: #ffffff}



.navBar

{color: #77797c;

font-family: Verdana, Helvetica, Arial, sans-serif;

font-size:  11px;

text-transform: uppercase}



a:visited

{color: #50525f}



a:link

{color: #8b3409}



a:hover

{color: #660000}



a:active

{background-color: #b1afad}



.footerNote

{background-color: #ffffff;

background-image: url(../images/line.gif);

background-position: right top;

background-repeat: repeat-x;

color: #77797c;

font-family: Verdana, Helvetica, Arial, sans-serif;

font-size:  10px}



BODY

{font-family: Verdana, Helvetica, Arial, sans-serif}

-->

</STYLE> <SCRIPT LANGUAGE="JavaScript">

<!--

function MM_swapImgRestore() { //v3.0

  var i,x,a=document.MM_sr; for(i=0;a&&i<a.length&&(x=a[i])&&x.oSrc;i++) x.src=x.oSrc;

}



function MM_preloadimages() { //v3.0

  var d=document; if(d.images){ if(!d.MM_p) d.MM_p=new Array();

    var i,j=d.MM_p.length,a=MM_preloadimages.arguments; for(i=0; i<a.length; i++)

    if (a[i].indexOf("#")!=0){ d.MM_p[j]=new Image; d.MM_p[j++].src=a[i];}}

}



function MM_findObj(n, d) { //v4.0

  var p,i,x;  if(!d) d=document; if((p=n.indexOf("?"))>0&&parent.frames.length) {

    d=parent.frames[n.substring(p+1)].document; n=n.substring(0,p);}

  if(!(x=d[n])&&d.all) x=d.all[n]; for (i=0;!x&&i<d.forms.length;i++) x=d.forms[i][n];

  for(i=0;!x&&d.layers&&i<d.layers.length;i++) x=MM_findObj(n,d.layers[i].document);

  if(!x && document.getElementById) x=document.getElementById(n); return x;

}



function MM_swapImage() { //v3.0

  var i,j=0,x,a=MM_swapImage.arguments; document.MM_sr=new Array; for(i=0;i<(a.length-2);i+=3)

   if ((x=MM_findObj(a[i]))!=null){document.MM_sr[j++]=x; if(!x.oSrc) x.oSrc=x.src; x.src=a[i+2];}

}

//-->

</SCRIPT> 

</HEAD>

<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LEFTMARGIN="0" TOPMARGIN="0" MARGINWIDTH="0" MARGINHEIGHT="0">

<TABLE WIDTH="101%" BORDER="0" CELLSPACING="0" CELLPADDING="0">

<TR>

<TD VALIGN="top" HEIGHT="75">

<TABLE WIDTH="100%" BORDER="0" CELLSPACING="0" CELLPADDING="0" HEIGHT="75">

<TR>

<TD BACKGROUND="../images/menubg95.jpg" HEIGHT="75">

<TABLE WIDTH="760" BORDER="0" CELLSPACING="0" CELLPADDING="0" ALIGN="center" HEIGHT="75">

<TR VALIGN="bottom">

<TD WIDTH="760" ALIGN="center" HEIGHT="50" COLSPAN="2">

<IMG SRC="../images/headertop.jpg" WIDTH="760" HEIGHT="50"></TD>

</TR>

<TR>

<TD HEIGHT="10" ALIGN="center" VALIGN="top" BGCOLOR="#333333" WIDTH="135">

<IMG SRC="../images/logoleft.jpg" WIDTH="135" HEIGHT="25" VSPACE="0" HSPACE="0" ALIGN="left">

</TD>

<TD CLASS="navBar" HEIGHT="25" ALIGN="center" VALIGN="middle" BGCOLOR="#333333" NOWRAP WIDTH="625" BACKGROUND="../images/menubg.jpg">

<CENTER>

<A HREF="http://icl.cs.utk.edu/papi/">

PAPI HOME

</A>

</CENTER>

</TD>

</TR>

<TR>

<TD HEIGHT="10" ALIGN="center" VALIGN="top" BGCOLOR="FFFFFF" WIDTH="135">

<IMG SRC="../images/logobottom.jpg" WIDTH="135" HEIGHT="20" VSPACE="0" HSPACE="0" ALIGN="left">

</TD>

<TD CLASS="navBar" HEIGHT="10" ALIGN="center" VALIGN="bottom" BGCOLOR="FFFFFF" WIDTH="625">

<IMG SRC="../images/white.jpg" WIDTH="625" HEIGHT="20" VSPACE="0" HSPACE="0" ALIGN="left">

</TD>

</TR>

</TABLE>

</TD>

</TR>

</TABLE>

</TD>

</TR>

<TR>

<TD VALIGN="top">

<TABLE WIDTH="760" BORDER="0" CELLSPACING="0" CELLPADDING="0" ALIGN="center" CLASS="style">

<TR>

<TD CLASS="STYLE">

<P>
<!-- .SH NAME -->
<A name=0>

     <H3>NAME</H3>

</A>
<BLOCKQUOTE>
PAPI_sprofil - generate PC histogram data from multiple code regions where hardware counter overflow occurs
<P>
<!-- .SH SYNOPSIS -->
</BLOCKQUOTE>
<A name=contents></A><H3>CONTENTS</H3></A>
<BLOCKQUOTE>
<A HREF=#1>Synopsis</A><BR>
<A HREF=#2>Description</A><BR>
<A HREF=#3>Structure Fields</A><BR>
<A HREF=#4>Arguments</A><BR>
<A HREF=#5>Return Values</A><BR>
<A HREF=#6>Errors</A><BR>
<A HREF=#7>Examples</A><BR>
<A HREF=#8>Bugs</A><BR>
<A HREF=#9>See Also</A><BR>
</BLOCKQUOTE>
<A name=10>

     <H3>SYNOPSIS</H3>

</A>
<BLOCKQUOTE>
<!-- .B C Interface -->
<B>C Interface</B> <!-- .nf -->
<PRE>
<!-- .B #include <papi.h> -->
<B>#include &lt;papi.h&gt;</B> 
<!-- .BI "int PAPI_sprofil(PAPI_sprofil_t * " prof, " int " profcnt, " int "  EventSet, -->
<B>int PAPI_sprofil(PAPI_sprofil_t * </B><I>prof,</I><B> int </B><I>profcnt,</I><B> int </B><I>EventSet,</I> 
<!-- .BI "                 int " EventCode, "  int "  threshold, "  int "  flags "  ); -->
<B>                 int </B><I>EventCode,</I><B>  int </B><I>threshold,</I><B>  int </B><I>flags</I><B></B><I>);</I> 
<!-- .fi -->
</PRE>
<!-- .LP -->
<P>
<!-- .B Fortran Interface -->
<B>Fortran Interface</B> <!-- .nf -->
<PRE>
<!-- .I The profiling routines have no Fortran interface. -->
<I>The profiling routines have no Fortran interface.</I> 
<!-- .fi -->
</PRE>
<P>
<!-- .SH DESCRIPTION -->
</BLOCKQUOTE>
<A name=2>

     <H3>DESCRIPTION</H3>

</A>
<BLOCKQUOTE>
<!-- .B PAPI_sprofil() -->
<B>PAPI_sprofil()</B> is a structure driven profiler that profiles one or more disjoint regions of code
in a single call. It accepts a pointer to
a preinitialized array of sprofil structures, and initiates profiling based on
the values contained in the array. Each structure in the array defines the
profiling parameters that are normally passed to
<!-- .B PAPI_profil(). -->
<B>PAPI_profil().</B> For more information on profiling, see:
<!-- .BR PAPI_pofil "(3)" -->
<A HREF="papi_pofil.html">PAPI_pofil (3)</A>
<P>
<!-- .SH STRUCTURE FIELDS -->
</BLOCKQUOTE>
<A name=3>

     <H3>STRUCTURE FIELDS</H3>

</A>
<BLOCKQUOTE>
<!-- .I *pr_base -->
<I>*pr_base</I> -- pointer to the base address of the buffer.
<!-- .LP -->
<P>
<!-- .I pr_size -->
<I>pr_size</I> -- the size of the histogram buffer in pr_base.
<!-- .LP -->
<P>
<!-- .I pr_off -->
<I>pr_off</I> -- the start address of&nbsp;the region to be profiled.
<!-- .LP -->
<P>
<!-- .I pr_scale -->
<I>pr_scale</I> -- the scaling factor applied to the buffer.
<!-- .LP -->
<P>
These fields are described in greater detail in the documentation for
<!-- .BR PAPI_pofil "(3)" -->
<A HREF="papi_pofil.html">PAPI_pofil (3)</A>
<P>
<!-- .SH ARGUMENTS -->
</BLOCKQUOTE>
<A name=4>

     <H3>ARGUMENTS</H3>

</A>
<BLOCKQUOTE>
<!-- .I *prof -->
<I>*prof</I> -- pointer to an array of PAPI_sprofil_t structures.
<!-- .LP -->
<P>
<!-- .I profcnt -->
<I>profcnt</I> -- number of structures in the prof array for hardware profiling.
<!-- .LP -->
<P>
<!-- .I EventSet  -->
<I>EventSet</I> -- The PAPI EventSet to profile. This EventSet is marked as profiling-ready, but profiling
doesn&#146;t actually start until a
<!-- .B PAPI_start() -->
<B>PAPI_start()</B> call is issued.
<!-- .LP -->
<P>
<!-- .I EventCode -->
<I>EventCode</I> -- Code of the Event in the EventSet to profile. This event must already be a member of the EventSet.
<!-- .LP -->
<P>
<!-- .I threshold  -->
<I>threshold</I> -- minimum number of events that must occur before the PC is sampled. If hardware overflow
is supported for your substrate, this threshold will trigger an interrupt when reached.
Otherwise, the counters will be sampled periodically and the PC will be recorded for the
first sample that exceeds the threshold. If the value of threshold is 0, profiling will be
disabled for this event.
<P>
<!-- .LP -->
<P>
<!-- .I flags  -->
<I>flags</I> -- bit pattern to control profiling behavior. Defined values are given in a table
in the documentation for
<!-- .BR PAPI_pofil "(3)" -->
<A HREF="papi_pofil.html">PAPI_pofil (3)</A>
<P>
<!-- .SH RETURN VALUES -->
</BLOCKQUOTE>
<A name=5>

     <H3>RETURN VALUES</H3>

</A>
<BLOCKQUOTE>
On success, this function returns
<!-- .B "PAPI_OK." -->
<B>PAPI_OK.</B> <BR>
 On error, a non-zero error code is returned.
<P>
<!-- .SH ERRORS -->
</BLOCKQUOTE>
<A name=6>

     <H3>ERRORS</H3>

</A>
<BLOCKQUOTE>
Error returns for
<!-- .B PAPI_sprofil() -->
<B>PAPI_sprofil()</B> are identical to those for
<!-- .BR PAPI_profil "(3)" -->
<A HREF="papi_profil.html">PAPI_profil (3)</A>
Please refer to that page for further details.
<P>
<!-- .SH EXAMPLES -->
</BLOCKQUOTE>
<A name=7>

     <H3>EXAMPLES</H3>

</A>
<BLOCKQUOTE>
<!-- .nf -->
<PRE>
<!-- .if t .ft CW -->
<TT>int retval;
unsigned long length;
PAPI_exe_info_t *prginfo;
unsigned short *profbuf1, *profbuf2, profbucket;
PAPI_sprofil_t sprof[3];
<P>
if ((prginfo = PAPI_get_executable_info()) == NULL)
  handle_error(1);
<P>
length = (unsigned long)(prginfo-&gt;text_end - prginfo-&gt;text_start);
<P>
/* Allocate 2 buffers of equal length */
profbuf1 = (unsigned short *)malloc(length);
profbuf2 = (unsigned short *)malloc(length);
if ((profbuf1 == NULL) || (profbuf2 == NULL))
  handle_error(1);
memset(profbuf1,0x00,length);
memset(profbuf2,0x00,length);
<P>
/* First buffer */
sprof[0].pr_base = profbuf1;
sprof[0].pr_size = length;
sprof[0].pr_off = (caddr_t) DO_FLOPS;
sprof[0].pr_scale = 0x10000;
<P>
/* Second buffer */
sprof[1].pr_base = profbuf2;
sprof[1].pr_size = length;
sprof[1].pr_off = (caddr_t) DO_READS;
sprof[1].pr_scale = 0x10000;
<P>
/* Overflow bucket */
sprof[2].pr_base = profbucket;
sprof[2].pr_size = 1;
sprof[2].pr_off = 0;
sprof[2].pr_scale = 0x0002;
<P>
if ((retval = PAPI_sprofil(sprof, EventSet, PAPI_FP_INS, 1000000,
                 PAPI_PROFIL_POSIX | PAPI_PROFIL_BUCKET_16)) != PAPI_OK)
  handle_error(retval);
<!-- .if t .ft P -->
</TT><!-- .fi -->
</PRE>
<P>
<!-- .SH BUGS -->
</BLOCKQUOTE>
<A name=8>

     <H3>BUGS</H3>

</A>
<BLOCKQUOTE>
These functions have no known bugs.
<P>
<!-- .SH SEE ALSO -->
</BLOCKQUOTE>
<A name=9>

     <H3>SEE ALSO</H3>

</A>
<BLOCKQUOTE>
<!-- .BR PAPI_profil "(3), " -->
<A HREF="papi_profil.html">PAPI_profil (3)</A>, 
<!-- .BR PAPI_get_executable_info "(3), " -->
<A HREF="papi_get_executable_info.html">PAPI_get_executable_info (3)</A>, 
<!-- .BR PAPI_overflow "(3) " -->
<A HREF="papi_overflow.html">PAPI_overflow (3)</A> 
</BLOCKQUOTE>
<P><HR>
<TABLE width=100%><TR> <TD width=33%><I>PAPI Programmer&#146;s Reference</I></TD> <TD width=33% align=center>PAPI_sprofil (3)</TD> <TD align=right width=33%><I>September, 2004</I></TD> </TR></TABLE>
<HR SIZE="1">

</TD>

</TR>

</TABLE>

</TD>

</TR>

<TR>

<TD VALIGN="top">

<TABLE WIDTH="760" BORDER="0" CELLSPACING="0" CELLPADDING="5" ALIGN="center">

<TR>

<TD>

</TD>

</TR>

<TR>

<TD HEIGHT="92">

<TABLE WIDTH="760" BORDER="0" CELLSPACING="0" CELLPADDING="0" ALIGN="center" VSPACE="0" HSPACE="0">

<TR VALIGN="top">

<TD ALIGN="left" BACKGROUND="../images/stripes2.jpg" ROWSPAN="2">&nbsp;

 

</TD>

<TD ALIGN="right" HEIGHT="39" BACKGROUND="../images/stripes2.jpg" WIDTH="280">

<IMG SRC="../images/trans.gif" WIDTH="280" HEIGHT="63" VSPACE="0" HSPACE="0">

</TD>

<TD ALIGN="left" HEIGHT="63" WIDTH="200" BACKGROUND="../images/spinbg.jpg">

<A HREF="http://icl.cs.utk.edu/" ONMOUSEOUT="MM_swapImgRestore()" ONMOUSEOVER="MM_swapImage('Image10','','../images/spinlogo.gif',1)">

<IMG NAME="Image10" BORDER="0" SRC="../images/stable.gif" WIDTH="200" HEIGHT="63" HSPACE="0" VSPACE="0" ALIGN="left" ALT="Innovative Computing Laboratory">

</A>

</TD>

<TD ALIGN="left" HEIGHT="0" ROWSPAN="2" VALIGN="top" WIDTH="140">

<DIV ALIGN="left">

<IMG SRC="../images/trans.gif" WIDTH="140" HEIGHT="75" BORDER="0" ALIGN="left" VSPACE="0" HSPACE="0">

</DIV>

</TD>

<TD ALIGN="left" ROWSPAN="2" VALIGN="top" WIDTH="140">

<IMG SRC="../images/rd.jpg" WIDTH="140" HEIGHT="75" BORDER="0" ALIGN="right" VSPACE="0" HSPACE="0" ALT="2001 R&amp;D Winner">

</TD>

<TD ALIGN="right" ROWSPAN="3" VALIGN="top" BGCOLOR="#FFFFFF">&nbsp;

 

</TD>

</TR>

<TR VALIGN="top">

<TD ALIGN="center" HEIGHT="22" ROWSPAN="2" VALIGN="TOP">

<SPAN CLASS="FOOTERNOTE">

Contact PAPI: 

<A HREF="mailto:papi@cs.utk.edu">

papi@cs.utk.edu</A>

</SPAN>

</TD>

<TD ALIGN="center" HEIGHT="11" WIDTH="200">

<A HREF="http://www.cs.utk.edu/" ONMOUSEOUT="MM_swapImgRestore()" ONMOUSEOVER="MM_swapImage('Image11','','../images/cssigon.gif',1)">

<IMG NAME="Image11" BORDER="0" SRC="../images/cssigoff.gif" WIDTH="200" HEIGHT="11" ALIGN="left" HSPACE="0" VSPACE="0" ALT="Computer Science Department">

</A>

</TD>

</TR>

<TR VALIGN="top">

<TD ALIGN="left">&nbsp;

 

</TD>

<TD ALIGN="CENTER" HEIGHT="11" WIDTH="200" VALIGN="top">

<A HREF="http://www.utk.edu/" ONMOUSEOUT="MM_swapImgRestore()" ONMOUSEOVER="MM_swapImage('Image12','','../images/utsigon.gif',1)">

<IMG NAME="Image12" BORDER="0" SRC="../images/utsigoff.gif" WIDTH="200" HEIGHT="11" VSPACE="0" HSPACE="0" ALIGN="left" ALT="University of Tennessee">

</A>

</TD>

<TD ALIGN="left" HEIGHT="0" COLSPAN="2" VALIGN="top">&nbsp;

 

</TD>

</TR>

</TABLE>

</TD>

</TR>

</TABLE>

</TD>

</TR>

<TR>

<TD VALIGN="top">&nbsp;

 

</TD>

</TR>

</TABLE>

</BODY>

</HTML>

